home *** CD-ROM | disk | FTP | other *** search
-
-
-
- Tk_CreateMainWindow(3)Tk Library Procedures
-
-
-
- _________________________________________________________________
-
- NAME
- Tk_CreateMainWindow, Tk_CreateWindow,
- Tk_CreateWindowFromPath, Tk_DestroyWindow,
- Tk_MakeWindowExist - create or delete window
-
- SYNOPSIS
- #include <tk.h>
-
- Tk_Window
- Tk_CreateMainWindow(_i_n_t_e_r_p, _s_c_r_e_e_n_N_a_m_e, _b_a_s_e_N_a_m_e, _c_l_a_s_s_N_a_m_e) |
-
- Tk_Window
- Tk_CreateWindow(_i_n_t_e_r_p, _p_a_r_e_n_t, _n_a_m_e, _t_o_p_L_e_v_S_c_r_e_e_n)
-
- Tk_Window
- Tk_CreateWindowFromPath(_i_n_t_e_r_p, _t_k_w_i_n, _p_a_t_h_N_a_m_e, _t_o_p_L_e_v_S_c_r_e_e_n)
-
- Tk_DestroyWindow(_t_k_w_i_n)
-
- Tk_MakeWindowExist(_t_k_w_i_n)
-
- ARGUMENTS
- Tcl_Interp *_i_n_t_e_r_p (out) Tcl interpreter to
- use for error report-
- ing. If no error
- occurs, then *_i_n_t_e_r_p
- isn't modified. For
- Tk_CreateMainWindow,
- this interpreter is
- associated per-
- manently with the
- created window, and
- Tk-related commands
- are bound into the
- interpreter.
-
- char *_s_c_r_e_e_n_N_a_m_e (in) String name of screen
- on which to create
- window. Has the form
- _d_i_s_p_l_a_y_N_a_m_e._s_c_r_e_e_n_N_u_m,
- where _d_i_s_p_l_a_y_N_a_m_e is
- the name of a display
- and _s_c_r_e_e_n_N_u_m is a
- screen number. If
- the dot and _s_c_r_e_e_n_N_u_m
- are omitted, the
- screen number
- defaults to 0. If
- _s_c_r_e_e_n_N_a_m_e is NULL or
- empty string,
-
-
-
- Tk 1
-
-
-
-
-
-
- Tk_CreateMainWindow(3)Tk Library Procedures
-
-
-
- defaults to contents
- of DISPLAY environ-
- ment variable.
-
- char *_b_a_s_e_N_a_m_e (in) Name to use for this
- main window. See
- below for details.
-
- char *_c_l_a_s_s_N_a_m_e (in) Class to use for |
- application and for |
- main window.
-
- Tk_Window _p_a_r_e_n_t (in) Token for the window
- that is to serve as
- the logical parent of
- the new window.
-
- char *_n_a_m_e (in) Name to use for this
- window. Must be
- unique among all
- children of the same
- _p_a_r_e_n_t.
-
- char *_t_o_p_L_e_v_S_c_r_e_e_n (in) Has same format as
- _s_c_r_e_e_n_N_a_m_e. If NULL,
- then new window is
- created as an inter-
- nal window. If non-
- NULL, new window is
- created as a top-
- level window on
- screen _t_o_p_L_e_v_S_c_r_e_e_n.
- If _t_o_p_L_e_v_S_c_r_e_e_n is an
- empty string (``'')
- then new window is
- created as top-level
- window of _p_a_r_e_n_t's
- screen.
-
- Tk_Window _t_k_w_i_n (in) Token for window.
-
- char *_p_a_t_h_N_a_m_e (in) Name of new window,
- specified as path
- name within applica-
- tion (e.g. .a.b.c).
- _________________________________________________________________
-
-
- DESCRIPTION
- The three procedures Tk_CreateMainWindow, Tk_CreateWindow,
- and Tk_CreateWindowFromPath are used to create new windows
- for use in Tk-based applications. Each of the procedures
-
-
-
- Tk 2
-
-
-
-
-
-
- Tk_CreateMainWindow(3)Tk Library Procedures
-
-
-
- returns a token that can be used to manipulate the window in
- other calls to the Tk library. If the window couldn't be
- created successfully, then NULL is returned and _i_n_t_e_r_p-
- >_r_e_s_u_l_t is modified to hold an error message.
-
- Tk supports three different kinds of windows: main windows,
- internal windows, and top-level windows. A main window is
- the outermost window corresponding to an application. Main
- windows correspond to the independent units of an applica-
- tion, such as a view on a file that is part of an editor, or
- a clock, or a terminal emulator. A main window is created
- as a child of the root window of the screen indicated by the
- _s_c_r_e_e_n_N_a_m_e. Each main window, and all its descendants, are
- typically associated with a single Tcl command interpreter.
- An internal window is an interior window of a Tk applica-
- tion, such as a scrollbar or menu bar or button. A top-
- level window is one that is created as a child of a screen's
- root window, rather than as an interior window, but which is
- logically part of some existing main window. Examples of
- top-level windows are pop-up menus and dialog boxes.
-
- Tk_CreateMainWindow creates a new main window and associates |
- its _i_n_t_e_r_p argument with that window and all its eventual |
- descendants. Tk_CreateMainWindow also carries out several |
- other actions to set up the new application. First, it adds |
- all the Tk commands to those already defined for _i_n_t_e_r_p. |
- Second, it turns the new window into a toplevel widget, |
- which will cause the X window to be created and mapped as |
- soon as the application goes idle. Third, |
- Tk_CreateMainWindow registers _i_n_t_e_r_p so that it can be
- accessed remotely by other Tk applications using the send
- command and the name _b_a_s_e_N_a_m_e. Normally, _b_a_s_e_N_a_m_e consists
- of the name of the application followed by a space and an
- identifier for this particular main window (if such an iden-
- tifier is relevant). For example, an editor named mx
- displaying the file foo.c would use ``mx foo.c'' as the
- basename. An application that doesn't usually have multiple
- instances, such as a clock program, would just use the name
- of the application, e.g. ``xclock''. If _b_a_s_e_N_a_m_e is already
- in use by some other registered interpreter, then
- Tk_CreateMainWindow extends _b_a_s_e_N_a_m_e with a number to pro-
- duce a unique name like ``mx foo.c #2'' or ``xclock #12''.
- This name is used both as the name of the window (returned
- by Tk_Name) and as the registered name of the interpreter. |
- Fourth, Tk_CreateMainWindow sets _c_l_a_s_s_N_a_m_e as the class of |
- the application (among other things, this is used for look- |
- ups in the option database), and also as the class of the |
- main widget.
-
- Either internal or top-level windows may be created by cal-
- ling Tk_CreateWindow. If the _t_o_p_L_e_v_S_c_r_e_e_n argument is NULL,
- then the new window will be an internal window. If
-
-
-
- Tk 3
-
-
-
-
-
-
- Tk_CreateMainWindow(3)Tk Library Procedures
-
-
-
- _t_o_p_L_e_v_S_c_r_e_e_n is non-NULL, then the new window will be a
- top-level window: _t_o_p_L_e_v_S_c_r_e_e_n indicates the name of a
- screen and the new window will be created as a child of the
- root window of _t_o_p_L_e_v_S_c_r_e_e_n. In either case Tk will con-
- sider the new window to be the logical child of _p_a_r_e_n_t: the
- new window's path name will reflect this fact, options may
- be specified for the new window under this assumption, and
- so on. The only difference is that new X window for a top-
- level window will not be a child of _p_a_r_e_n_t's X window. For
- example, a pull-down menu's _p_a_r_e_n_t would be the button-like
- window used to invoke it, which would in turn be a child of
- the menu bar window. A dialog box might have the
- application's main window as its parent. This approach
- means that all the windows of an application fall into a
- hierarchical arrangement with a single logical root: the
- application's main window.
-
- Tk_CreateWindowFromPath offers an alternate way of specify-
- ing new windows. In Tk_CreateWindowFromPath the new window
- is specified with a token for any window in the target
- application (_t_k_w_i_n), plus a path name for the new window.
- It produces the same effect as Tk_CreateWindow and allows
- both top-level and internal windows to be created, depending
- on the value of _t_o_p_L_e_v_S_c_r_e_e_n. In calls to
- Tk_CreateWindowFromPath, as in calls to Tk_CreateWindow, the
- parent of the new window must exist at the time of the call,
- but the new window must not already exist.
-
- In truth, the window-creation procedures don't actually
- issue the command to X to create a window. Instead, they
- create a local data structure associated with the window and
- defer the creation of the X window. The window will actu-
- ally be created by the first call to Tk_MapWindow. Deferred
- window creation allows various aspects of the window (such
- as its size, background color, etc.) to be modified after
- its creation without incurring any overhead in the X server.
- When the window is finally mapped all of the window attri-
- butes can be set while creating the window.
-
- The value returned by a window-creation procedure is not the
- X token for the window (it can't be, since X hasn't been
- asked to create the window yet). Instead, it is a token for
- Tk's local data structure for the window. Most of the Tk
- library procedures take Tk_Window tokens, rather than X
- identifiers. The actual X window identifier can be
- retrieved from the local data structure using the
- Tk_WindowId macro; see the manual entry for Tk_WindowId for
- details.
-
- Tk_DestroyWindow deletes a window and all the data strutures
- associated with it, including any event handlers created
- with Tk_CreateEventHandler. In addition, Tk_DestroyWindow
-
-
-
- Tk 4
-
-
-
-
-
-
- Tk_CreateMainWindow(3)Tk Library Procedures
-
-
-
- will delete any children of _t_k_w_i_n recursively (where chil-
- dren are defined in the Tk sense, consisting of all windows
- that were created with the given window as _p_a_r_e_n_t). If
- _t_k_w_i_n was created by Tk_CreateInternalWindow then event
- handlers interested in destroy events are invoked immedi-
- ately. If _t_k_w_i_n is a top-level or main window, then the
- event handlers will be invoked later, after X has seen the
- request and returned an event for it.
-
- If a window has been created but hasn't been mapped, so no X
- window exists, it is possible to force the creation of the X
- window by calling Tk_MakeWindowExist. This procedure issues
- the X commands to instantiate the window given by _t_k_w_i_n.
-
-
- KEYWORDS
- create, deferred creation, destroy, display, internal win-
- dow, main window, register, screen, top-level window, window
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Tk 5
-
-
-
-